Crate gix

This crate provides the Repository abstraction which serves as a hub into all the functionality of git.

It’s powerful and won’t sacrifice performance while still increasing convenience compared to using the sub-crates individually. Sometimes it may hide complexity under the assumption that the performance difference doesn’t matter for all but the fewest tools out there, which would be using the underlying crates directly or file an issue.

The prelude and extensions

With use git_repository::prelude::* you should be ready to go as it pulls in various extension traits to make functionality available on objects that may use it.

The method signatures are still complex and may require various arguments for configuration and cache control.

Most extensions to existing objects provide an obj_with_extension.attach(&repo).an_easier_version_of_a_method() for simpler call signatures.

ThreadSafe Mode

By default, the Repository isn’t Sync and thus can’t be used in certain contexts which require the Sync trait.

To help with this, convert it with .into_sync() into a ThreadSafeRepository.

Object-Access Performance

Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it’s vital to understand which cache levels exist and how to leverage them.

When accessing an object, the first cache that’s queried is a memory-capped LRU object cache, mapping their id to data and kind. It has to be specifically enabled a Repository. On miss, the object is looked up and if a pack is hit, there is a small fixed-size cache for delta-base objects.

In scenarios where the same objects are accessed multiple times, the object cache can be useful and is to be configured specifically using the object_cache_size(…) method.

Use the cache-efficiency-debug cargo feature to learn how efficient the cache actually is - it’s easy to end up with lowered performance if the cache is not hit in 50% of the time.

Terminology

WorkingTree and WorkTree

When reading the documentation of the canonical gix-worktree program one gets the impression work tree and working tree are used interchangeably. We use the term work tree only and try to do so consistently as its shorter and assumed to be the same.

Cargo-features

To make using sub-crates easier these are re-exported into the root of this crate. Here we list how to access nested plumbing crates which are otherwise harder to discover:

git_repository::

• odb
  • pack
• protocol
  • transport
    • [packetline][protocol::transport::packetline]

libgit2 API to gix

This section is a ‘striving to be complete’ mapping from libgit2 APIs to the respective methods in gix.

• git2::Repository::open() ➡ gix::open()
• git2::Repository::open_bare() ➡ ❌
• git2::Repository::open_from_env() ➡ gix::ThreadSafeRepository::open_with_environment_overrides()
• git2::Repository::open_ext() ➡ gix::open_opts()
• git2::Repository::revparse() ➡ gix::Repository::rev_parse()
• git2::Repository::revparse_single() ➡ gix::Repository::rev_parse_single()
• git2::Repository::revwalk() ➡ gix::Repository::rev_walk()

Feature Flags

Mutually Exclusive Network Client

Either async-* or blocking-* versions of these toggles may be enabled at a time.

• async-network-client — Make gix-protocol available along with an async client.

• async-network-client-async-std — Use this if your crate uses async-std as runtime, and enable basic runtime integration when connecting to remote servers.

• blocking-network-client — Make gix-protocol available along with a blocking client.

• blocking-http-transport-curl — Stacks with blocking-network-client to provide support for HTTP/S using curl, and implies blocking networking as a whole.

• blocking-http-transport-reqwest — Stacks with blocking-network-client to provide support for HTTP/S using reqwest, and implies blocking networking as a whole.

• blocking-http-transport-reqwest-rust-tls — Stacks with blocking-http-transport-reqwest and enables HTTPS via the rustls crate. Note that https isn’t available without a selection.

• blocking-http-transport-reqwest-native-tls — Stacks with blocking-http-transport-reqwest and enables HTTPS via the native-tls crate. Note that https isn’t available without a selection.

Other

• serde — Data structures implement serde::Serialize and serde::Deserialize.

• progress-tree — Re-export the progress tree root which allows to obtain progress from various functions which take impl gix::Progress.

• comfort (enabled by default) — Various progress-related features that improve the look of progress message units.

• cache-efficiency-debug — Print debugging information about usage of object database caches, useful for tuning cache sizes.

Performance

• max-performance-safe (enabled by default) — Activate features that maximize performance, like usage of threads, zlib-ng and access to caching in object databases, skipping the ones known to cause compile failures on some platforms.

• hp-tempfile-registry — The tempfile registry uses a better implementation of a thread-safe hashmap, relying on an external crate. This may be useful when tempfiles are created and accessed in a massively parallel fashion and you know that this is indeed faster than the simpler implementation that is the default.

• pack-cache-lru-static — Provide a fixed-size allocation-free LRU cache for packs. It’s useful if caching is desired while keeping the memory footprint for the LRU-cache itself low.

• pack-cache-lru-dynamic — Provide a hash-map based LRU cache whose eviction is based a memory cap calculated from object data.

• max-performance — Activate other features that maximize performance, like usage of threads, zlib-ng and access to caching in object databases. Note that some platforms might suffer from compile failures, which is when max-performance-safe should be used.

• fast-sha1 — If enabled, use assembly versions of sha1 on supported platforms. This might cause compile failures as well which is why it can be turned off separately.

• regex — For use in rev-parse, which provides searching commits by running a regex on their message.

  If disabled, the text will be search verbatim in any portion of the commit message, similar to how a simple unanchored regex of only ‘normal’ characters would work.

Re-exports

• pub use gix_actor as actor;
• pub use gix_attributes as attrs;
• pub use gix_commitgraph as commitgraph;
• pub use gix_credentials as credentials;
• pub use gix_date as date;
• pub use gix_features as features;
• pub use gix_fs as fs;
• pub use gix_glob as glob;
• pub use gix_hash as hash;
• pub use gix_hashtable as hashtable;
• pub use gix_ignore as ignore;
• pub use gix_lock as lock;
• pub use gix_negotiate as negotiate;
• pub use gix_object as objs;
• pub use gix_object::bstr;
• pub use gix_odb as odb;
• pub use gix_prompt as prompt;
• pub use gix_protocol as protocol;
• pub use gix_ref as refs;
• pub use gix_refspec as refspec;
• pub use gix_sec as sec;
• pub use gix_tempfile as tempfile;
• pub use gix_trace as trace;
• pub use gix_traverse as traverse;
• pub use gix_url as url;
• pub use gix_utils as utils;

Modules

• attributes
• clone
• commit
• config
• create
• diff
• discover
• env
  Utilities to handle program arguments and other values of interest.
• head
• id
• index
  Feature Flags
• init
• interrupt
  Process-global interrupt handling
• mailmap
• object
• open
• parallel
  Run computations in parallel, or not based the parallel feature toggle.
• path
• prelude
• progress
• reference
• remote
• repository
• revision
  Revisions is the generalized notion of a commit.
• shallow
• state
  Not to be confused with ‘status’.
• tag
• threading
  Type definitions for putting shared ownership and synchronized mutation behind the threading feature toggle.
• worktree

Structs

• Commit
  A decoded commit object with access to its owning repository.
• Head
  The head reference, as created from looking at .git/HEAD, able to represent all of its possible states.
• Id
  An ObjectId with access to a repository.
• Object
  A decoded object with a reference to its owning repository.
• ObjectDetached
  A detached, self-contained object, without access to its source repository.
• Reference
  A reference that points to an object or reference, with access to its source repository.
• Remote
  A remote which represents a way to interact with hosts for remote clones of the parent repository.
• Repository
  A thread-local handle to interact with a repository from a single thread.
• Tag
  A decoded tag object with access to its owning repository.
• ThreadSafeRepository
  An instance with access to everything a git repository entails, best imagined as container implementing Sync + Send for most for system resources required to interact with a git repository which are loaded in once the instance is created.
• Tree
  A decoded tree object with access to its owning repository.
• Url
  A URL with support for specialized git related capabilities.
• Worktree
  A worktree checkout containing the files of the repository in consumable form.
• oid
  A borrowed reference to a hash identifying objects.

Enums

• ObjectId
  An owned hash identifying objects, most commonly Sha1

Traits

• Progress
  A trait for describing hierarchical progress.

Functions

• discover
  See ThreadSafeRepository::discover(), but returns a Repository instead.
• init
  See ThreadSafeRepository::init(), but returns a Repository instead.
• init_bare
  See ThreadSafeRepository::init(), but returns a Repository instead.
• open
  See ThreadSafeRepository::open(), but returns a Repository instead.
• open_opts
  See ThreadSafeRepository::open_opts(), but returns a Repository instead.
• prepare_clone
  Create a platform for configuring a clone with main working tree from url to the local path, using default options for opening it (but amended with using configuration from the git installation to ensure all authentication options are honored).
• prepare_clone_bare
  Create a platform for configuring a bare clone from url to the local path, using default options for opening it (but amended with using configuration from the git installation to ensure all authentication options are honored).

Type Definitions

• OdbHandle
  A handle for finding objects in an object database, abstracting away caches for thread-local use.
• RefStore
  The standard type for a store to handle git references.